Initialization.rst: fix superscripts and render code as code #531

RL-S · 2024-06-07T19:26:03Z

Two superscripts weren't rendered as such, because the leading (escaped) space before ':sup:<num>' was missing. Also, the table of command line arguments was rendered as text, rendering double dashes as em or en dashes (at least in my browser). Finally, removed two extraneous words in the "Initialization by struct" paragraph. Also, why is this .rst, but other parts are .md? I think that leads to a lot of code being simply rendered as italics: anything inside single backticks without "code::" before it.

Two superscripts weren't rendered as such, because the leading (escaped) space before ':sup:`<num>`' was missing. Also, the table of command line arguments was rendered as text, rendering double dashes as em or en dashes (at least in my browser). Finally, removed two extraneous words in the "Initialization by struct" paragraph. Also, why is this .rst, but other parts are .md? I think that leads to a lot of code being simply rendered as italics: anything inside single backticks without "code::" before it.

masterleinad

Looks good to me! Thanks!

ajpowelsnl

Just a few details to fix up

ajpowelsnl · 2024-07-03T17:48:20Z

docs/source/ProgrammingGuide/Initialization.rst

@@ -63,26 +63,26 @@ Table 5.1: Command-line options for Kokkos::initialize

  * - Argument
    - Description
-  * - --kokkos-help --help
+  * - :code:`--kokkos-help --help`


I think it's just my_kokkos_executable --kokkos-help

ajpowelsnl · 2024-07-03T17:55:05Z

docs/source/ProgrammingGuide/Initialization.rst

@@ -100,14 +100,17 @@ The values are case insensitive.
 5.2 Initialization by environment variable
 ------------------------------------------

-Instead of using command-line arguments, one may use environment variables. The environment variables are identical to the arguments in Table 5.1 but they are upper case and the dash is replaced by an underscore. For example, if we want to set the number of threads to 3, we have
+Instead of using command-line arguments, one may use environment variables. The environment variables are identical to the arguments in Table 5.1 but they are upper case and the dash is replaced by an underscore. For example, if we want to set the number of threads to 3, we may use
+


Would you please link to table 5.1?

By link, I meant a URL one can click for additional information. Is "< Table clio-pts>" a clickable URL?

It's supposed to be one, yes. You click it, and it jumps to Table 5.1. For that, I put an anchor above it, in line 60:
.. Table_cli-opts:
I'm not an expert in reStructured text, and neither is GitHub's preview, so references are a bit iffy. But the syntax
`Table 5.1 <Table_cli-opts>`_
is supposed to display 'Table 5.1' and the reference target is what's within the angle braces (< >). The underscore at the end is necessary, but I don't know, why.

ajpowelsnl · 2024-07-03T17:58:53Z

docs/source/ProgrammingGuide/Initialization.rst

 5.3 Initialization by struct
 ----------------------------

-Instead of giving `Kokkos::initialize() <../API/core/initialize_finalize/initialize.html>`_ command-line arguments, one may directly pass in initialization parameters using the `Kokkos::InitializationSettings` struct.  If one wants to set a options using the struct, one can use the set functions `set_xxx` where `xxx` is the identical to the arguments in Table 5.1 where the dash has been replaced by an underscore. To check if a variable has been set, one can use the `has_xxx` functions. Finally, to get the value that was set, one can use the `get_xxx` functions.
+Instead of giving `Kokkos::initialize() <../API/core/initialize_finalize/initialize.html>`_ command-line arguments, one may directly pass in initialization parameters using the `Kokkos::InitializationSettings` struct.  If one wants to set a options using the struct, one can use the functions `set_xxx` where `xxx` is identical to the arguments in Table 5.1 where the dash has been replaced by an underscore. To check if a variable has been set, one can use the `has_xxx` functions. Finally, to get the value that was set, one can use the `get_xxx` functions.


A few comments:

Please link to Table 5.1

In the "If one wants to set a options using the struct," clause, please remove the "a"; the sentence should read, "If one wants to set options using the struct, one can use the functions set_xxx where xxx is identical to the arguments in Table 5.1 where the dash has been replaced by an underscore. "

ajpowelsnl · 2024-07-03T17:59:43Z

ping @RL-S

response to kokkos#531 (review) Inserted custom anchor to allow referencing Table 5.1 and used it for all *three* references in the text, removed extraneous 'a' as suggested, and removed `--help` after `--kokkos-help`

RL-S · 2024-07-13T17:59:45Z

ping @RL-S

Was on holiday until yesterday. See new commit, should resolve it.

ajpowelsnl

It's good once the question around a working link to Table-5.1 is finalized.

ajpowelsnl · 2024-07-15T15:43:41Z

docs/source/ProgrammingGuide/Initialization.rst

@@ -49,40 +49,42 @@ Kokkos chooses the two spaces using the following list:
 8. `Kokkos::Threads`
 9. `Kokkos::Serial`

-The highest execution space in the list that is enabled is Kokkos' default execution space, and the highest enabled host execution space is Kokkos' default host execution space. For example, if  `Kokkos::Cuda`, `Kokkos::OpenMP`, and `Kokkos::Serial` are enabled, then `Kokkos::Cuda` is the default execution space and `Kokkos::OpenMP` is the default host execution space.:sup:`1`  In cases where the highest enabled backend is a host parallel execution space the `DefaultExecutionSpace` and the `DefaultHostExecutionSpace` will be the same.
+The highest execution space in the list that is enabled is Kokkos' default execution space, and the highest enabled host execution space is Kokkos' default host execution space. For example, if  `Kokkos::Cuda`, `Kokkos::OpenMP`, and `Kokkos::Serial` are enabled, then `Kokkos::Cuda` is the default execution space and `Kokkos::OpenMP` is the default host execution space\ :sup:`1`.  In cases where the highest enabled backend is a host parallel execution space the `DefaultExecutionSpace` and the `DefaultHostExecutionSpace` will be the same.


Just out of curiosity, is the "highest" execution space formally a Kokkos convention, something approximating operator precedence, or is it a concept we just expect everyone to understand automatically? If it's not been formalized, perhaps a sentence or two defining it might be useful ...?

ajpowelsnl · 2024-07-15T18:28:45Z

docs/source/ProgrammingGuide/Initialization.rst

@@ -100,14 +100,17 @@ The values are case insensitive.
 5.2 Initialization by environment variable
 ------------------------------------------

-Instead of using command-line arguments, one may use environment variables. The environment variables are identical to the arguments in Table 5.1 but they are upper case and the dash is replaced by an underscore. For example, if we want to set the number of threads to 3, we have
+Instead of using command-line arguments, one may use environment variables. The environment variables are identical to the arguments in Table 5.1 but they are upper case and the dash is replaced by an underscore. For example, if we want to set the number of threads to 3, we may use
+


By link, I meant a URL one can click for additional information. Is "< Table clio-pts>" a clickable URL?

ajpowelsnl · 2024-07-15T18:31:08Z

docs/source/ProgrammingGuide/Initialization.rst

 5.3 Initialization by struct
 ----------------------------

-Instead of giving `Kokkos::initialize() <../API/core/initialize_finalize/initialize.html>`_ command-line arguments, one may directly pass in initialization parameters using the `Kokkos::InitializationSettings` struct.  If one wants to set a options using the struct, one can use the set functions `set_xxx` where `xxx` is the identical to the arguments in Table 5.1 where the dash has been replaced by an underscore. To check if a variable has been set, one can use the `has_xxx` functions. Finally, to get the value that was set, one can use the `get_xxx` functions.
+Instead of giving `Kokkos::initialize() <../API/core/initialize_finalize/initialize.html>`_ command-line arguments, one may directly pass in initialization parameters using the `Kokkos::InitializationSettings` struct.  If one wants to set options using the struct, one can use the functions `set_xxx` where `xxx` is identical to the arguments in `Table 5.1 <Table_cli-opts>`_ where the dash has been replaced by an underscore. To check if a variable has been set, one can use the `has_xxx` functions. Finally, to get the value that was set, one can use the `get_xxx` functions.


Is there API documentation on using the struct for initialization settings? If not, that might be something to do, comparing one method to the other. I have the same question as above about the link to Table 5.1.

masterleinad approved these changes Jun 7, 2024

View reviewed changes

masterleinad mentioned this pull request Jun 18, 2024

Correct display of superscripts #544

Closed

Merge branch 'main' into patch-1

8c436a0

ajpowelsnl requested changes Jul 3, 2024

View reviewed changes

Initialization.rst: response to ajpowelsnl

2ce6439

response to kokkos#531 (review) Inserted custom anchor to allow referencing Table 5.1 and used it for all *three* references in the text, removed extraneous 'a' as suggested, and removed `--help` after `--kokkos-help`

masterleinad requested a review from ajpowelsnl July 15, 2024 14:42

ajpowelsnl approved these changes Jul 15, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initialization.rst: fix superscripts and render code as code #531

Initialization.rst: fix superscripts and render code as code #531

RL-S commented Jun 7, 2024

masterleinad left a comment

ajpowelsnl left a comment

ajpowelsnl Jul 3, 2024

ajpowelsnl Jul 3, 2024

ajpowelsnl Jul 15, 2024

RL-S Jul 16, 2024 •

edited

Loading

ajpowelsnl Jul 3, 2024

ajpowelsnl commented Jul 3, 2024

RL-S commented Jul 13, 2024

ajpowelsnl left a comment

ajpowelsnl Jul 15, 2024

ajpowelsnl Jul 15, 2024

ajpowelsnl Jul 15, 2024

Initialization.rst: fix superscripts and render code as code #531

Are you sure you want to change the base?

Initialization.rst: fix superscripts and render code as code #531

Conversation

RL-S commented Jun 7, 2024

masterleinad left a comment

Choose a reason for hiding this comment

ajpowelsnl left a comment

Choose a reason for hiding this comment

ajpowelsnl Jul 3, 2024

Choose a reason for hiding this comment

ajpowelsnl Jul 3, 2024

Choose a reason for hiding this comment

ajpowelsnl Jul 15, 2024

Choose a reason for hiding this comment

RL-S Jul 16, 2024 • edited Loading

Choose a reason for hiding this comment

ajpowelsnl Jul 3, 2024

Choose a reason for hiding this comment

ajpowelsnl commented Jul 3, 2024

RL-S commented Jul 13, 2024

ajpowelsnl left a comment

Choose a reason for hiding this comment

ajpowelsnl Jul 15, 2024

Choose a reason for hiding this comment

ajpowelsnl Jul 15, 2024

Choose a reason for hiding this comment

ajpowelsnl Jul 15, 2024

Choose a reason for hiding this comment

RL-S Jul 16, 2024 •

edited

Loading